Skip to main content

Authorize integration

In order to access, add, update, receive data from Pio using the API with integration you will need a token to authenticate. In the next section we'll discuss how to obtain this token, assuming you have registered your integration. This token is used to authenticate and passed in the header of a HTTP request to Pio API.

info

At the moment the access_token doesn't expire unless explicitly revoked or integration/shop is deactivated

Pio API has standard authorization process and follows OAuth 2.0 framework. To make sure that authorization work smoothly, make sure that there's a user in Pio system with organization and shop setup. Pio API authorization can be done as follows:

  1. Have client_id, client_secret handy and working redirect_url/callback)url ready for the complete oauth flow.
  2. Now that you have created an integration this needs to be authorized against an organization in Pio. This can be done by logging into pio with you admin user via this URL via a browser https://app.test.pio.com/raw/openapi_auth/authorize_form?client_id=<your-client-id>&redirect_uri=<your-redirect-url>.
  • client_id (mandatory) as a URL parameter. You can also pass other parameters in the same URL, if they are required to
  • redirect_uri (mandatory) used to redirect the user back to your integration after they accept the authorization request.
  • state (optional): If set, is included in the query arguments of the redirect back to your integraion. Use if it's needed to match the original request to the final callback.
  1. When entering the url above with your client_id you should get a login window like this if you are not already logged in: Pio Authorize login
  2. Once logged in with an Admin user you should see a similar screen to the one below Pio Authorize view This authorize form shows the name of your integration and all the scope you are requesting.
  3. Once the Pio user has pressed Authorize, they will be redirected back to callback_url. This url will contain the code which is essential for next step.
info

The code is visible in the url in the browser.

  1. The hmac can be used to verify that the redirect actually came from Pio. To verify the signature, remove the hmac=...& part of the query string, generate a HMAC-SHA256 signature from the remaining parts and verify it matches the provided hmac. Example can be found here
  2. Using code obtained from step above, you can now call API to get access_token; you'll need to pass code, client_id and client_secret

If something goes wrong during the entire process you can still resume from the last successful step.

You can also repeat these steps if you would like to authorize towards more shops.ยด

caution

Keep this access_token stored and safe, you'll need to make Pio user login again if you lose the token